Templates for Composite Controls

This topic describes the design-time and run-time template of a composite control.

Whether it is creating, using or extending a composite control, templates are needed to be defined by the developer writing the composite control. Templates are needed for both design time and run time.

In this section, lets see how the design time and run time can be represented and what information is vital for the control's existence.

Design-time Representation

The design-time template of the control is defined on thetoHTML()function which is written for every composite control. The following is the skeleton for such a definition.

<composite-control-type-name>.prototype.toHTML= function()
{
	return <template-as-string>;
}

it is necessary that this function returns the HTML as string, so the framework can load it properly and return it as HTML. The HTML element, once created here, can be accessed from any part of the composite control as follows:

var htmlElement = this.htmlElement();

A sample definition for a simple HelloWorld control is as follows:

HelloWorld.prototype.toHTML= function()
{
	return	"<div id='helloworldTemplate' xfTemplate='xhelloworld' movable='true' resizable='true' \
					layout='vertical' class='v_layout' defaultCursor='default' defaultWidth='300' \
					style='height:30px;overflow:visible' >\
				<img id='moveHandle' style='left:2' ondragstart='return false' \
						src='/cordys/cas/xforms/images/designtime/move.gif'/>\
				<div class='simplecontainer extensionbox' \ movable='false' resizable='false'> \
						Hello World ! \
				</div>\
			</div>";
}

The following table explains every attribute, property, and node in the HTML definition above:

Attribute	Description
id	Mandatory. Denotes the ID of the design time control template.
xfTemplate	Mandatory. Denotes the XForm template name based on which the control's properties are defined. This is usually "x" followed by the name of the control.
movable	Mandatory. Defines whether this control can be moved in design time or not. Values can betrueorfalse.
resizable	Mandatory. Defines whether this control can be resized in design time or not. Values can betrueorfalse.
visible	Optional. Denotes whether the control is visible at run time or not. Values can betrueorfalse.
noLayout	Optional. Defines whether the control is constraint to a specific layout on the XForm. If this istrue, then the control will not have any anchoring feature, and layout changes on the XForm or on the parent control will not influence this control. In most cases, for controls that are invisible at run time, this property istrue. But this can also be set totruefor controls like statusbar, so that you can decide and position the control always on the bottom.
layout	Optional. Defines the default layout of the control on the form. It can bevertical, horizontal, orfree. Though this is set, the layout preference will be followed based on the parent control or XForm.
class	Optional. A class can be set for composite controls in design time. In most cases it has the layout class (for examplev_layout), but it can be of any value.
defaultCursor	Mandatory. Denotes what is the cursor when focused on the control. This can bedefaultormoveor anything definable by the style cursor attribute.
defaultWidth	Optional. Denotes the width of the control.
style	Optional. Any style settings for the control can be defined here. Height is one such attribute which can only be defined here.
img	Optional. An image tag is usually added to every composite control which is movable. This is the image handle with which the control can be moved.
div	Optional. The DIV inside the composite control is called the child container of a composite control and can hold any data inside it. In case of HelloWorld, it carries just the text inside it. In case of the WebNavigator control, it can contain the Tree library.

For more variations of design time HTML representations for a composite control, look into the default composite controls at the following location:

<cordys-install-dir>\<your-instance-dir>\web\cas\xforms\designerlibrary\controls

and

<cordys-install-dir>\<your-instance-dir>\web\cas\xforms\designerlibrary\controls\extensions

Run-time Representation

The run-time template of every composite control represents how the control will look in run time. This is defined inside thetoXFormMarkup()method. The following is the skeleton code for such a definition.

<composite-control-type-name>.prototype.toXFormMarkup = function()
{
	if (! this.m_xmlProperties)
	{
		this.m_xmlProperties = this.designerWindow().getPropertiesNode(<tag-name>);

		// mandatory properties
		this.m_xmlProperties.setAttribute("xformextendedname", <composite-control-name>);
		this.m_xmlProperties.setAttribute("id", <id>);
		this.m_xmlProperties.setAttribute("namespace", <library-name>);
		
		//other properties here
	}
	return this.m_xmlProperties;
}

The above code creates the XML properties once, and returns it every time if already created, thereby being performance centric. Once created, the run-time representation can be accessed anywhere inside the composite control as follows:

var properties = this.toXFormMarkup();

A sample definition for a simple HelloWorld control is as follows.

HelloWorld.prototype.toXFormMarkup = function()
{
	if (!this.xformMarkup)
	{
		this.xformMarkup = this.designerView.getPropertiesNode("div");
		this.xformMarkup.setAttribute("xformextendedname", "helloworld");
		this.xformMarkup.setAttribute("id", "");
		this.xformMarkup.text = "Hello World !";

		// custom properties
		this.xformMarkup.setAttribute("caption", this.xformMarkup.text);
		this.xformMarkup.setAttribute("namespace", "mycontrols.runtimelibrary.HelloWorld");
	}
	return this.xformMarkup;
}

The following table explains the attributes used in the run-time representation above.

Attribute	Description
xformextendedname	Mandatory. Denotes that this is a composite control. It is the name of the composite control without spaces in between.
id	Mandatory. Denotes the ID of the control in run time, using which the control is accessed.
namespace	Required. This denotes the namespace of the run-time library if there is one. Usually every design-time library will have a run-time library, but it is not mandatory. The namespace is synonymous to the java packaging structure that isfolder-name.TypeName. For example, for the Statusbar control, it iswcp.library.ui.StatusBar.

All other additional properties set on top of these attributes denote implementation specific to each control.

pp108 : Templates for Composite Controls

Templates for Composite Controls

Design-time Representation

Run-time Representation